Search and lyrics topic
Search the server, read its suggestions and instant mixes, and read, upload and find lyrics.
Search, suggestions and instant mix
Search hints
final hints = await jellyfin.search.hints(
query: 'pink floyd',
includeItemTypes: const [
JellyfinItemKind.musicAlbum,
JellyfinItemKind.musicArtist,
JellyfinItemKind.audio,
],
limit: 30,
);
for (final h in hints.items) {
print('${h.type}: ${h.name}');
}
hints() returns a JellyfinQueryResult<JellyfinSearchHint>, a flat
list with itemId, name, matchedTerm, type, mediaType, run time
and a primaryImageTag for images.url(), in the User data and images topic.
For search with the full item filters, use items.list(searchTerm:).
Suggestions
suggestions.list() answers a flat feed of items the server picks for
the user, of any kind:
final picks = await jellyfin.suggestions.list(
mediaType: const [JellyfinMediaType.audio],
type: const [JellyfinItemKind.musicAlbum, JellyfinItemKind.audio],
limit: 30,
);
For movie rows grouped by reason, see the TV, movies and live TV topic.
Instant mix
The server builds a list of related tracks from a seed: a song, an album, an artist, a playlist or a music genre.
final mix = await jellyfin.instantMix.fromItem(itemId: track.id, limit: 50);
for (final item in mix.items) {
print('${item.name} - ${item.albumArtist}');
}
final fromSong = await jellyfin.instantMix.fromSong(songId: track.id);
final fromAlbum = await jellyfin.instantMix.fromAlbum(albumId: album.id);
final fromArtist = await jellyfin.instantMix.fromArtist(artistId: artist.id);
final fromList = await jellyfin.instantMix.fromPlaylist(playlistId: playlist.id);
// A genre seeds a mix by its music-genre id.
final rock = await jellyfin.genres.musicGenre(
name: 'Rock',
parentId: musicLibraryId,
);
final fromGenre = await jellyfin.instantMix.fromItem(itemId: rock!.id);
Each call returns a JellyfinQueryResult<JellyfinItem>. Take a genre's
id from a track's genreItems, from genres.list(parentId: musicLibraryId) or from genres.musicGenre() (see
the Library topic): a generic genre id answers an empty mix.
fromArtist() takes a MusicArtist id, from a track's artistItems:
the Person ids that artists answers give an empty mix too.
Lyrics
Reading lyrics
final lyrics = await jellyfin.audio.lyrics(itemId: track.id);
if (lyrics == null) {
// no lyrics
} else if (lyrics.hasCues) {
print(lyrics.toLrc(enhanced: true)); // enhanced LRC, a time for each word
} else if (lyrics.isSynced) {
print(lyrics.toLrc()); // LRC, a time for each line
} else {
print(lyrics.toPlainText());
}
jellyfin.lyrics.forItem(itemId:) is the same call, deprecated in 0.4.2. JellyfinLyrics
holds the lines, each with startTicks (in 100-nanosecond units),
start as a Duration, text and cues: word-level
JellyfinLyricCues with their own start and end. metadata holds the
file's tags (JellyfinLyricMetadata: artist, album, title, offset) when
the server sends them. toLrc(enhanced: true) writes the lines that have
cues in enhanced LRC and the others as plain LRC.
lyrics() returns null on a 404, which the server answers both for a
track without lyrics and for an id that names no item.
No route serves the original .lrc or .txt file: the lyrics route
answers the parsed lyrics as JSON. Rebuild a file with toLrc() or
toPlainText().
Uploading and deleting
final bytes = await File('track.lrc').readAsBytes();
final uploaded = await jellyfin.lyrics.upload(
itemId: track.id,
fileName: 'track.lrc',
body: bytes,
);
await jellyfin.lyrics.delete(itemId: track.id);
The server picks the parser from the file extension, and upload()
returns the lyrics as it parsed them.
Remote search and download
With a lyrics provider plugin on the server:
final hits = await jellyfin.lyrics.searchRemote(itemId: track.id);
for (final hit in hits) {
print('${hit.providerName}: ${hit.id} (${hit.lyrics?.lines.length} lines)');
}
final preview = await jellyfin.lyrics.previewRemote(lyricId: hits.first.id);
final attached = await jellyfin.lyrics.downloadRemote(
itemId: track.id,
lyricId: hits.first.id,
);
Each hit is a JellyfinRemoteLyric with id, providerName and the
lyrics as JellyfinLyrics when the provider sent them. previewRemote()
fetches a result without attaching it; downloadRemote() attaches it to
the track.
Classes
- JellyfinInstantMixApi Search and lyrics
-
/{ItemType}/{id}/InstantMix— server-side radio. - JellyfinLyrics Search and lyrics
-
Payload of
GET /Audio/{id}/Lyrics(LyricDto). - JellyfinLyricsApi Search and lyrics
-
/Audio/.../Lyricsand/Providers/Lyrics/{id}— lyric upload, removal, and remote (provider) search/download. - JellyfinSearchApi Search and lyrics
-
/Search/Hints— fast, type-as-you-go search. - JellyfinSuggestionsApi Search and lyrics
-
/Items/Suggestions— server-curated picks for the current user.